COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	%Start Part 1 of 6 concep.tex
C00036 ENDMK
C⊗;
%Start Part 1 of 6 concep.tex
\input macros
\draftremark{\hbox{\vbox{\hbox{\prmeleven 88-003}\hbox{\prmeleven Draft distributed to X3J13 March 1988}}}}
\tolerance=2500
\def\bookline{\CLOS\  Specification}
\def\chapline{Programmer Interface Concepts}
\def\newpage{\vfill\eject}

\beginChapter 1.{Common Lisp Object System Specification}%
{Programmer Interface Concepts}{Programmer Interface Concepts}

Authors: Daniel G. Bobrow, Linda G. DeMichiel, Richard P.
Gabriel,\hfil\break Sonya E. Keene, Gregor Kiczales, and David A.
Moon.

{\ifdraft Draft Dated: June 15, 1988\hfil\break\fi}
All Rights Reserved

The distribution and publication of this document are not restricted.
In order to preserve the integrity of the specification, any
publication or distribution must reproduce this document in its
entirety, preserve its formatting, and include this title page.

For information about obtaining the sources for this document, send
an Internet message to 
common-lisp-object-system-specification-request@sail.stanford.edu.

The authors wish to thank Patrick Dussud, Kenneth Kahn,
Jim Kempf,\hfil\break Larry Masinter, Mark Stefik,
Daniel L. Weinreb, and Jon L White\hfil\break
for their contributions to this document.

\vskip 2pc
At the X3J13 meeting on June 15, 1988, the following motion was
adopted:

``The X3J13 Committee hereby accepts chapters 1 and 2
of the Common Lisp Object System, as defined in document
88-002R, for inclusion in the Common Lisp language being
specified by this committee. Subsequent changes will be handled
through the usual editorial and cleanup processes.''

\endTitlePage

\beginSection{Introduction}

The \CLOS\ is an object-oriented extension to Common Lisp as defined
in {\it Common Lisp: The Language}, by Guy L. Steele Jr. It is based on
generic functions, multiple inheritance, declarative method
combination, and a meta-object protocol.

The first two chapters of this specification present a description of
the standard Programmer Interface for the \CLOS.  The first chapter
contains a description of the concepts of the \CLOS, and the second
contains a description of the functions and macros in the \CLOS\
Programmer Interface.  The chapter ``The \CLOS\ Meta-Object
Protocol'' describes how the \CLOS\ can be customized.

The fundamental objects of the \CLOS\ are classes, instances,
generic functions, and methods. 

A {\bit class\/} object determines the structure and behavior of a set
of other objects, which are called its {\bit instances}. 
Every Common Lisp object is an {\bit
instance\/} of a class.  The class of an object determines the set of
operations that can be performed on the object.

A {\bit generic function\/} is a function whose behavior depends on the
classes or identities of the arguments supplied to it.  A generic
function object contains a set of methods, a lambda-list, a
method combination type, and other information.  The {\bit methods} define
the class-specific behavior and operations of the generic function; a
method is said to {\bit specialize\/} a generic function.  When invoked,
a generic function executes a subset of its methods based on the
classes of its arguments.

A generic function can be used in 
the same ways that an ordinary function can be used in Common Lisp; in
particular, a generic function can be used as an argument to {\bf
funcall} and {\bf apply} and can be given a global or a local name.

A {\bit method\/} is an object that contains a method function, a sequence of
{\bit parameter specializers\/} that specify when the given method is
applicable, and a sequence of {\bit qualifiers\/} that is used by the
{\bit method combination\/} facility to distinguish among methods.  Each
required formal parameter of each method has an associated parameter
specializer, and the method will be invoked only on arguments that
satisfy its parameter specializers.

The method combination facility controls the selection of methods, the
order in which they are run, and the values that are returned by the
generic function.  The \CLOS\ offers a default method combination type
and provides a facility for declaring new types of method combination.

\endSection%{Introduction}

\beginSection{Error Terminology}

The terminology used in this document to describe erroneous
situations differs from the terminology used in {\it Common Lisp:
The Language}, by Guy L. Steele Jr.  This terminology involves {\bit
situations}; a situation is the evaluation of an expression in some
specific context. For example, a situation might be the invocation of
a function on arguments that fail to satisfy some specified
constraints.

In the specification of the \CLOS, the behavior of programs in all situations
is described, and the options available to the implementor are defined. No
implementation is allowed to extend the syntax or semantics of the \OS\ except
as explicitly defined in the \OS\ specification. In particular, no
implementation is allowed to extend the syntax of the \OS\ in such a way that
ambiguity between the specified syntax of \OS\ and those extensions is
possible.

``When situation $S$ occurs, an error is signaled.''

This terminology has the following meaning:

\beginlist

\item{\bull} If this situation occurs, an error will be signaled in
the interpreter and in code compiled under all compiler safety
optimization levels.

\item{\bull} Valid programs may rely on the fact that an error will be
signaled in the interpreter and in code compiled under all compiler
safety optimization levels.

\item{\bull} Every implementation is required to detect such an error
in the interpreter and in code compiled under all compiler safety
optimization levels.

\endlist

``When situation $S$ occurs, an error should be signaled.''

This terminology has the following meaning:

\beginlist

\item{\bull} If this situation occurs, an error will be signaled at
least in the interpreter and in code compiled under the safest
compiler safety optimization level.

\item{\bull} Valid programs may not rely on the fact that an error will be
signaled.

\item{\bull} Every implementation is required to detect such an error
at least in the interpreter and in code compiled under the safest
compiler safety optimization level.

\item{\bull} When an error is not signaled, the results are undefined (see
below).

\endlist

``When situation $S$ occurs, the results are undefined.''

This terminology has the following meaning:

\beginlist

\item{\bull} If this situation occurs, the results are unpredictable.  The
results may range from harmless to fatal.

\item{\bull} Implementations are allowed to detect this situation and
signal an error, but no implementation is required to detect the
situation.

\item{\bull} No valid program may depend on the effects of this
situation, and all valid programs are required to treat the effects 
of this situation as unpredictable.

\endlist

``When situation $S$ occurs, the results are unspecified.''

This terminology has the following meaning:

\beginlist

\item{\bull} The effects of this situation are not specified in
the \OS, but the effects are harmless.

\item{\bull} Implementations are allowed to specify the effects of
this situation.

\item{\bull} No portable program can depend on the effects of this
situation, and all portable programs are required to treat the situation
as unpredictable but harmless.

\endlist

``The \CLOS\ may be extended to cover situation $S$\negthinspace.''

The meaning of this terminology is that an implementation is free to treat
situation $S$ in one of three ways:

\beginlist

\item{\bull} When situation $S$ occurs, an error is signaled at least
in the interpreter and in code compiled under the safest compiler
safety optimization level.

\item{\bull} When situation $S$ occurs, the results are undefined.

\item{\bull} When situation $S$ occurs, the results are defined and
specified.

\endlist

In addition, this terminology has the following meaning:

\beginlist

\item{\bull} No portable program can depend on the effects of this
situation, and all portable programs are required to treat the situation
as undefined.

\endlist

``Implementations are free to extend the syntax $S$\negthinspace.''

This terminology has the following meaning:

\beginlist

\item{\bull} Implementations are allowed to define unambiguous extensions
to syntax $S$\negthinspace.

\item{\bull} No portable program can depend on this extension,
all portable programs are required to treat the syntax
as meaningless.

\endlist

The \CLOS\ specification may disallow certain extensions while allowing others.

\endSection%{Error Terminology}

\beginSection{Classes}

A {\bit class\/} is an object that determines the structure and behavior 
of a set of other objects, which are called its {\bit instances}.   

A class can inherit structure and behavior from other classes.  
A class whose definition refers to other classes for the purpose of
inheriting from them is said to be a {\bit subclass\/} of each of
those classes.  The classes that are designated for purposes of
inheritance are said to be {\bit superclasses\/}
of the inheriting class.

A class can have a {\bit name}. The function {\bf class-name} takes a
class object and returns its name. The name of an anonymous class is
{\bf nil}.  A symbol can {\bit name\/} a class.  The function {\bf
find-class} takes a symbol and returns the class that the symbol
names. A class has a {\bit proper name\/} if the name is a symbol
and if the name of the class
names that class.  That is, a class~$C$ has the {\bit proper
name\/}~$S$ if $S=$ {\tt (class-name $C$)} and $C=$ {\tt (find-class
$S$)}.  Notice that it is possible for {\tt (find-class $S\sub 1$)}
$=$ {\tt (find-class $S\sub 2$)} and $S\sub 1\neq S\sub 2$.
If $C=$ {\tt (find-class $S$)}, we say that $C$ is the {\bit class named}
$S$.

A class $C\sub{1}$ is a {\bit direct superclass\/} of a class
$C\sub{2}$ if $C\sub{2}$ explicitly designates $C\sub{1}$ as a
superclass in its definition.  In this case $C\sub{2}$ is a {\bit
direct subclass\/} of $C\sub{1}$.  A class $C\sub{n}$ is a {\bit
superclass\/} of a class $C\sub{1}$ if there exists a series of
classes $C\sub{2},\ldots,C\sub{n-1}$ such that $C\sub{i+1}$ is a
direct superclass of $C\sub{i}$ for $1 \leq i<n$.  In this case, 
$C\sub{1}$ is a {\bit subclass\/} of $C\sub{n}$.  A class is
considered neither a superclass nor a subclass of itself.  That is, if
$C\sub{1}$ is a superclass of $C\sub{2}$, then $C\sub{1} \neq
C\sub{2}$.  The set of classes consisting of some given
class $C$ along with all of its superclasses is called ``$C$ and its
superclasses.''

Each class has a {\bit class precedence list}, which is a total ordering
on the set of the given class and its superclasses.  The total ordering
is expressed as a list ordered from most specific to least specific.
The class precedence list is used in several ways.  In general, more
specific classes can {\bit shadow}, or override, features that would
otherwise be inherited from less specific classes.  The method selection
and combination process uses the class precedence list to order methods
from most specific to least specific. 
 
When a class is defined, the order in which its direct superclasses
are mentioned in the defining form is important.  Each class has a
{\bit local precedence order\/}, which is a list consisting of the
class followed by its direct superclasses in the order mentioned
in the defining form.

A class precedence list is always consistent with the local precedence
order of each class in the list.  The classes in each local precedence
order appear within the class precedence list in the same order.  If
the local precedence orders are inconsistent with each other, no class
precedence list can be constructed, and an error is signaled.
The class precedence list and its computation is discussed
in the section ``Determining the Class Precedence List.''

Classes are organized into a {\bit directed acyclic graph}.  There are
two distinguished classes, named {\bf t} and {\bf standard-object}.
The class named {\bf t} has no superclasses.  It is a superclass of
every class except itself.  The class named {\bf standard-object} is
an instance of the class {\bf standard-class} and is a superclass of
every class that is an instance of {\bf standard-class} except itself.

There is a mapping from the Common Lisp Object System class space into
the Common Lisp type space.  Many of the standard Common Lisp types
specified in {\it Common Lisp: The Language\/} have a corresponding
class that has the same name as the type.  Some Common Lisp types do
not have a corresponding class.  The integration of the type and class
systems is discussed in the section ``Integrating Types and Classes.''

Classes are represented by objects that are themselves
instances of classes.  The class of the class of an object is termed
the {\bit metaclass\/} of that object.  When no misinterpretation is
possible, the term {\bit metaclass\/} will be used to refer to a class
that has instances that are themselves classes.  The metaclass
determines the form of inheritance used by the classes that are its
instances and the representation of the instances of those classes.
The \CLOS\ provides a default metaclass, {\bf standard-class}, that is
appropriate for most programs.  The meta-object protocol provides
mechanisms for defining and using new metaclasses.

Except where otherwise specified, all classes mentioned in this
chapter are instances of the class {\bf standard-class}, all generic
functions are instances of the class {\bf standard-generic-function},
and all methods are instances of the class {\bf standard-method}.

\beginsubSection{Defining Classes}

The macro {\bf defclass} is used to define a new named class.  The
syntax for {\bf defclass} is given in Figure~2-1.

The definition of a class includes:

\beginlist

\item{\bull} The name of the new class. For newly defined classes
this name is a proper name.

\item{\bull} The list of the direct superclasses of the new class. 

\item{\bull} A set of {\bit slot specifiers}.  Each slot specifier
includes the name of the slot and zero or more {\bit slot options}.  A
slot option pertains only to a single slot. If a class definition
contains two slot specifiers with the same name, an error is signaled.

\item{\bull} A set of {\bit class options}.  Each class option pertains 
to the class as a whole.  
\endlist

The slot options and class options of the {\bf defclass} form provide
mechanisms for the following:

\beginlist

\item{\bull} Supplying a default initial value form for a given slot.  

\item{\bull} Requesting that methods for generic functions
be automatically generated for reading or writing slots. 

\item{\bull} Controlling whether a given slot is shared by instances
of the class or whether each instance of the class has its own slot.

\item{\bull} Supplying a set of initialization arguments and initialization
argument defaults to be used in instance creation.

%\item{\bull} Requesting that a constructor function be automatically
%generated for making instances of the new class.

\item{\bull} Indicating that the metaclass is to be other than the default.

\item{\bull} Indicating the expected type for the value stored in the slot.

\item{\bull} Indicating the documentation string for the slot.

\endlist 

\endsubSection%{Defining Classes}

\goodbreak

\beginsubSection{Creating Instances of Classes}

The generic function {\bf make-instance} creates and returns a new
instance of a class.  The \OS\ provides several mechanisms for
specifying how a new instance is to be initialized.  For example, it
is possible to specify the initial values for slots in newly created
instances either by giving arguments to {\bf make-instance} or by
providing default initial values.  Further initialization activities
can be performed by methods written for generic functions that are
part of the initialization protocol.  The complete initialization
protocol is described in the section ``Object Creation and
Initialization.''

\endsubSection%{Creating Instances of Classes}

\beginsubSection{Slots}

An object that has {\bf standard-class} as its metaclass has zero or
more named slots.  The slots of an object are determined by the class
of the object.  Each slot can hold one value.  The name of a slot is a
symbol that is syntactically valid for use as a Common Lisp variable
name.

When a slot does not have a value, the slot is said to be {\bit
unbound}.  When an unbound slot is read, the generic
function {\bf slot-unbound} is invoked. The system-supplied primary method
for {\bf slot-unbound} signals an error.

The default initial value form for a slot is defined by the \hbox{{\bf
:initform}} slot option. When the {\bf :initform} form is used to
supply a value, it is evaluated in the lexical environment in which
the {\bf defclass} form was evaluated. The {\bf :initform} along with
the lexical environment in which the {\bf defclass} form was evaluated
is called a {\bit captured\/} {\bf :initform}. See the section
``Object Creation and Initialization'' for more details.

A {\bit local slot\/} is defined to be a slot that is visible to exactly
one instance, namely the one in which the slot is allocated.  A {\bit
shared slot\/} is defined to be a slot that is visible to more than one
instance of a given class and its subclasses.

A class is said to {\bit define\/} a slot with a given name when
the {\bf defclass} form for that class contains a slot specifier with
that name.  Defining a local slot does not immediately create a slot;
it causes a slot to be created each time an instance of the class is
created.  Defining a shared slot immediately creates a slot.

The {\bf :allocation} slot option to {\bf defclass} controls the kind
of slot that is defined.  If the value of the {\bf :allocation} slot
option is {\bf :instance}, a local slot is created.  If the value of
{\bf :allocation} is {\bf :class}, a shared slot is created.

A slot is said to be {\bit accessible\/} in an instance of a class if
the slot is defined by the class of the instance or is inherited from
a superclass of that class.  At most one slot of a given name can be
accessible in an instance.  A shared slot defined by a class is
accessible in all instances of that class.  A detailed explanation of
the inheritance of slots is given in the section ``Inheritance of
Slots and Slot Options.''

\endsubSection%{Slots}

\beginsubSection{Accessing Slots}

Slots can be accessed in two ways: by use of the primitive function
{\bf slot-value} and by use of generic functions generated by the {\bf
defclass} form.

The function {\bf slot-value} can be used with any of the slot names
specified in the {\bf defclass} form to access a specific slot
accessible in an instance of the given class.

The macro {\bf defclass} provides syntax for generating methods to
read and write slots.  If a {\bit reader\/} is requested, a method is
automatically generated for reading the value of the slot, but no
method for storing a value into it is generated.  If a {\bit writer\/}
is requested, a method is automatically generated for storing a value
into the slot, but no method for reading its value is generated.  If
an {\bit accessor\/} is requested, a method for reading the value of
the slot and a method for storing a value into the slot are
automatically generated.  Reader and writer methods are implemented
using {\bf slot-value}.

When a reader or writer is specified for a slot, the name of the
generic function to which the generated method belongs is directly
specified.  If the name specified for the writer option is the symbol
{\it name}, the name of the generic function for writing the slot
is the symbol {\it name}, and the generic function takes two
arguments: the new value and the instance, in that order.  If the name
specified for the accessor option is the symbol {\it name}, the
name of the generic function for reading the slot is the symbol {\it
name\/}, and the name of the generic function for writing the slot is
the list {\tt (setf {\it name\/})}.

A generic function created or modified by supplying reader, writer, or
accessor slot options can be treated exactly as an ordinary generic
function.

Note that {\bf slot-value} can be used to read or write the value of a
slot whether or not reader or writer methods exist for that slot.
When {\bf slot-value} is used, no reader or writer methods are
invoked.

The macro {\bf with-slots} can be used to establish a lexical
environment in which specified slots are lexically available as if they
were variables.  The macro {\bf with-slots} invokes the function {\bf
slot-value} to access the specified slots.

The macro {\bf with-accessors} can be used to establish a lexical
environment in which specified slots are lexically available through
their accessors as if they were variables.  The macro {\bf
with-accessors} invokes the appropriate accessors to access the
specified slots. Any accessors specified by {\bf with-accessors} must
already have been defined before they are used.

\endsubSection%{Accessing Slots}
\endSection%{Classes}
%End Part 1 of 6 concep.tex